home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / icu-1.3.1 / icu-bin / include / format.h < prev    next >
C/C++ Source or Header  |  2000-02-23  |  10KB  |  233 lines
  1. /*
  2. ********************************************************************************
  3. *                                                                              *
  4. * COPYRIGHT:                                                                   *
  5. *   (C) Copyright Taligent, Inc.,  1997                                        *
  6. *   (C) Copyright International Business Machines Corporation,  1997-1999      *
  7. *   Licensed Material - Program-Property of IBM - All Rights Reserved.         *
  8. *   US Government Users Restricted Rights - Use, duplication, or disclosure    *
  9. *   restricted by GSA ADP Schedule Contract with IBM Corp.                     *
  10. *                                                                              *
  11. ********************************************************************************
  12. *
  13. * File FORMAT.H
  14. *
  15. * Modification History:
  16. *
  17. *   Date        Name        Description
  18. *   02/19/97    aliu        Converted from java.
  19. *   03/17/97    clhuang     Updated per C++ implementation.
  20. *   03/27/97    helena      Updated to pass the simple test after code review.
  21. ********************************************************************************
  22. */
  23. // *****************************************************************************
  24. // This file was generated from the java source file Format.java
  25. // *****************************************************************************
  26.  
  27. #ifndef FORMAT_H
  28. #define FORMAT_H
  29.  
  30.  
  31. #include "utypes.h"
  32. #include "unistr.h"
  33. #include "fmtable.h"
  34. #include "fieldpos.h"
  35. #include "parsepos.h"
  36.  
  37. /** 
  38.  * Base class for all formats.  This is an abstract base class which
  39.  * specifies the protocol for classes which convert other objects or
  40.  * values, such as numeric values and dates, and their string
  41.  * representations.  In some cases these representations may be
  42.  * localized or contain localized characters or strings.  For example,
  43.  * a numeric formatter such as DecimalFormat may convert a numeric
  44.  * value such as 12345 to the string "$12,345".  It may also parse
  45.  * the string back into a numeric value.  A date and time formatter
  46.  * like SimpleDateFormat may represent a specific date, encoded
  47.  * numerically, as a string such as "Wednesday, February 26, 1997 AD".
  48.  * <P>
  49.  * Many of the concrete subclasses of Format employ the notion of
  50.  * a pattern.  A pattern is a string representation of the rules which
  51.  * govern the interconversion between values and strings.  For example,
  52.  * a DecimalFormat object may be associated with the pattern
  53.  * "$#,##0.00;($#,##0.00)", which is a common US English format for
  54.  * currency values, yielding strings such as "$1,234.45" for 1234.45,
  55.  * and "($987.65)" for 987.6543.  The specific syntax of a pattern
  56.  * is defined by each subclass.
  57.  * <P>
  58.  * Even though many subclasses use patterns, the notion of a pattern
  59.  * is not inherent to Format classes in general, and is not part of
  60.  * the explicit base class protocol.
  61.  * <P>
  62.  * Two complex formatting classes bear mentioning.  These are
  63.  * MessageFormat and ChoiceFormat.  ChoiceFormat is a subclass of
  64.  * NumberFormat which allows the user to format different number ranges
  65.  * as strings.  For instance, 0 may be represented as "no files", 1 as
  66.  * "one file", and any number greater than 1 as "many files".
  67.  * MessageFormat is a formatter which utilizes other Format objects to
  68.  * format a string containing with multiple values.  For instance,
  69.  * A MessageFormat object might produce the string "There are no files
  70.  * on the disk MyDisk on February 27, 1997." given the arguments 0,
  71.  * "MyDisk", and the date value of 2/27/97.  See the ChoiceFormat
  72.  * and MessageFormat headers for further information.
  73.  * <P>
  74.  * If formatting is unsuccessful, a failing UErrorCode is returned when
  75.  * the Format cannot format the type of object, otherwise if there is
  76.  * something illformed about the the Unicode replacement character
  77.  * 0xFFFD is returned.
  78.  * <P>
  79.  * If there is no match when parsing, a parse failure UErrorCode is
  80.  * retured for methods which take no ParsePosition.  For the method
  81.  * that takes a ParsePosition, the index parameter is left unchanged.
  82.  * <P>
  83.  * [Subclassing.] All base classes that provide static functions that
  84.  * create objects for Locales must implement the following static:
  85.  * <pre>
  86.  * .      public static const Locale* getAvailableLocales(long&)
  87.  * </pre>
  88.  */
  89. class U_I18N_API Format {
  90. public:
  91.  
  92.     virtual ~Format();
  93.  
  94.     /**
  95.      * Return true if the given Format objects are semantically equal.
  96.      * Objects of different subclasses are considered unequal.
  97.      */
  98.     virtual bool_t operator==(const Format& other) const = 0;
  99.  
  100.     /**
  101.      * Return true if the given Format objects are not semantically
  102.      * equal.
  103.      */
  104.     bool_t operator!=(const Format& other) const { return !operator==(other); }
  105.  
  106.     /**
  107.      * Clone this object polymorphically.  The caller is responsible
  108.      * for deleting the result when done.
  109.      */
  110.     virtual Format* clone() const = 0;
  111.  
  112.     /**
  113.      * Formats an object to produce a string.
  114.      *
  115.      * @param obj       The object to format.
  116.      * @param result    Output parameter which will be filled in with the
  117.      *                  formatted string.
  118.      * @param status    Output parameter filled in with success or failure status.
  119.      * @return          Reference to 'result' parameter.
  120.      */
  121.     UnicodeString& format(const Formattable& obj,
  122.                           UnicodeString& result,
  123.                           UErrorCode& status) const;
  124.  
  125.     /**
  126.      * Format an object to produce a string.  This is a pure virtual method which
  127.      * subclasses must implement. This method allows polymorphic formatting
  128.      * of Formattable objects. If a subclass of Format receives a Formattable
  129.      * object type it doesn't handle (e.g., if a numeric Formattable is passed
  130.      * to a DateFormat object) then it returns a failing UErrorCode.
  131.      *
  132.      * @param obj           The object to format.
  133.      * @param toAppendTo    Where the text is to be appended.
  134.      * @param pos           On input: an alignment field, if desired.
  135.      *                      On output: the offsets of the alignment field.
  136.      * @param status        Output param filled with success/failure status.
  137.      * @return              The value passed in as toAppendTo (this allows chaining,
  138.      *                      as with UnicodeString::append())
  139.      */
  140.     virtual UnicodeString& format(const Formattable& obj,
  141.                                   UnicodeString& toAppendTo,
  142.                                   FieldPosition& pos,
  143.                                   UErrorCode& status) const = 0;
  144.  
  145.     /**
  146.      * Parse a string to produce an object.  This is a pure virtual
  147.      * method which subclasses must implement.  This method allows
  148.      * polymorphic parsing of strings into Formattable objects.
  149.      * <P>
  150.      * Before calling, set parse_pos.index to the offset you want to
  151.      * start parsing at in the source.  After calling, parse_pos.index
  152.      * is the end of the text you parsed.  If error occurs, index is
  153.      * unchanged.
  154.      * <P>
  155.      * When parsing, leading whitespace is discarded (with successful
  156.      * parse), while trailing whitespace is left as is.
  157.      * <P>
  158.      * Example:
  159.      * <P>
  160.      * Parsing "_12_xy" (where _ represents a space) for a number,
  161.      * with index == 0 will result in the number 12, with
  162.      * parse_pos.index updated to 3 (just before the second space).
  163.      * Parsing a second time will result in a failing UErrorCode since
  164.      * "xy" is not a number, and leave index at 3.
  165.      * <P>
  166.      * Subclasses will typically supply specific parse methods that
  167.      * return different types of values. Since methods can't overload
  168.      * on return types, these will typically be named "parse", while
  169.      * this polymorphic method will always be called parseObject.  Any
  170.      * parse method that does not take a parse_pos should set status
  171.      * to an error value when no text in the required format is at the
  172.      * start position.
  173.      *
  174.      * @param source    The string to be parsed into an object.
  175.      * @param result    Formattable to be set to the parse result.
  176.      *                  If parse fails, return contents are undefined.
  177.      * @param parse_pos The position to start parsing at. Upon return
  178.      *                  this param is set to the position after the
  179.      *                  last character successfully parsed. If the
  180.      *                  source is not parsed successfully, this param
  181.      *                  will remain unchanged.
  182.      */
  183.     virtual void parseObject(const UnicodeString& source,
  184.                              Formattable& result,
  185.                              ParsePosition& parse_pos) const = 0;
  186.  
  187.     /**
  188.      * Parses a string to produce an object. This is a convenience method
  189.      * which calls the pure virtual parseObject() method, and returns a
  190.      * failure UErrorCode if the ParsePosition indicates failure.
  191.      *
  192.      * @param source    The string to be parsed into an object.
  193.      * @param result    Formattable to be set to the parse result.
  194.      *                  If parse fails, return contents are undefined.
  195.      * @param status    Output param to be filled with success/failure
  196.      *                  result code.
  197.      */
  198.     void parseObject(const UnicodeString& source,
  199.                      Formattable& result,
  200.                      UErrorCode& status) const;
  201.  
  202.     /**
  203.      * Returns a unique class ID POLYMORPHICALLY.  Pure virtual method.
  204.      * This method is to implement a simple version of RTTI, since not all
  205.      * C++ compilers support genuine RTTI.  Polymorphic operator==() and
  206.      * clone() methods call this method.
  207.      * <P>
  208.      * Concrete subclasses of Format must implement getDynamicClassID()
  209.      * and also a static method and data member:
  210.      *
  211.      *      static UClassID getStaticClassID() { return (UClassID)&fgClassID; }
  212.      *      static char fgClassID;
  213.      *
  214.      * @return          The class ID for this object. All objects of a
  215.      *                  given class have the same class ID.  Objects of
  216.      *                  other classes have different class IDs.
  217.      */
  218.     virtual UClassID getDynamicClassID() const = 0;
  219.  
  220. protected:
  221.     /**
  222.      * Default constructor for subclass use only.  Does nothing.
  223.      */
  224.     Format();
  225.  
  226.     Format(const Format&); // Does nothing; for subclasses only
  227.  
  228.     Format& operator=(const Format&); // Does nothing; for subclasses
  229. };
  230.  
  231. #endif // _FORMAT
  232. //eof
  233.